home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 3 / Cream of the Crop 3.iso / clipper / ks94an.zip / PUSHSET.HDR < prev    next >
Text File  |  1994-04-25  |  3KB  |  98 lines
  1. /******************************************************************************
  2.                  The Klipper Library, for CA-Clipper 5.x
  3.         Copyright (c), 1994, Wallace Information Systems Engineering
  4.  
  5. FUNCTION:
  6.  
  7. _PushSet(nSet,xVal) --> nStackSpaceRemaining
  8.  
  9. PARAMETERS:
  10.  
  11. nSet  : The Clipper SET() number of the setting to push
  12. xVal  : The value to be pushed onto the setting stack
  13.  
  14. SHORT:
  15.  
  16. Push a Clipper set() setting onto a SetStack() stack.
  17.  
  18. DESCRIPTION:
  19.  
  20. _PushSet(), _PopSet(), and _PeekSet() are a set of functions that allow you
  21. to save and retrieve any of Clipper's SET settings by pushing and popping
  22. from an internal stack.
  23.  
  24. All three functions have a stack that allows up to 10 settings to be saved
  25. for each of Clipper's 38 SET settings.
  26.  
  27. _PushSet() accepts TWO parameters, the first - nSet - corresponds to each
  28. of Clipper's numeric SET() settings.  You should use the Clipper
  29. Pre-processor directives for referencing these settings.
  30.  
  31. For example, to save the setting of SET EXACT, specify:
  32.  
  33. _PushSet(_SET_EXACT,<value>)
  34.  
  35. _PushSet()'s second parameter - xVal - is the value to be saved. _PushSet()
  36. is the only function that takes more than one function argument/parameter.
  37.  This can be of any data type used by SET() (ie, Char, Num, or Logical).
  38.  
  39. All Push/Pop operations use the LIFO method.  That is, the last value
  40. pushed onto the stack for any given set stack is the first one popped off
  41. of the stack.
  42.  
  43. The functions maintain separate stacks for each of the 38 different
  44. SET settings.  So, pushing a value onto the _SET_EXACT stack does not
  45. affect the _SET_DEVICE stack, or any other stack.
  46.  
  47. When a particular stack is full, any attempt to push another value onto
  48. that stack will be ignored and -1 will be returned indicating an
  49. "error condition."
  50.  
  51. Likewise, any attempt to pop more values off the stack than have been
  52. pushed onto the stack will return NIL.
  53.  
  54. To facilitate stack management, the function _CheckSet() can be used
  55. to determine the number of values currently on any given stack.  Using
  56. this function, you can determine if there are any values on the stack
  57. before attempting to pop them, and also, conversely, whether there is any
  58. room left on the stack before attempting to push new values.
  59.  
  60. The function _PeekSet() can be used to return the value of any given
  61. stack without actually popping it's value off the stack.  This allows you
  62. to use _PeekSet() in a similar manner as _CheckSet() to determine if there
  63. is a value on the stack before attempting to pop it.
  64.  
  65. _PeekSet() cannot tell you, however, if there is any room left on a stack.
  66. You must use _CheckSet() for that purpose.
  67.  
  68. NOTE:
  69.  
  70. This code is already available for compiling under DEMOS\SETSTACK.
  71.  
  72. EXAMPLE:
  73.  
  74. This example shows the full range of Push/Pop/Peek/Check usage filling and
  75. emptying a stack:
  76.  
  77. i = 1
  78.  
  79. while _CheckSet(_SET_DECIMALS) >= 1
  80.  
  81.     // space still available on stack
  82.  
  83.     _PushSet(_SET_DECIMALS,i++)
  84.     ? 'Remaining Space on Stack: '+str(_CheckSet(_SET_DECIMALS))
  85.  
  86. end
  87.  
  88. while _PeekSet(_SET_DECIMALS) != NIL
  89.  
  90.     // more values to pop...
  91.  
  92.     set(_SET_DECIMALS,_PopSet(_SET_DECIMALS))
  93.     ? 2/3, 'Remaining Space on Stack: '+str(_CheckSet(_SET_DECIMALS))
  94.  
  95. end
  96.  
  97. ******************************************************************************/
  98.